package com.smart.community.region.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.commons.result.Result;
import com.smart.community.commons.result.PageResult;
import com.smart.community.region.dto.CommunityDTO;
import com.smart.community.region.dto.CommunityQueryDTO;
import com.smart.community.region.entity.Community;
import com.smart.community.region.entity.Building;
import com.smart.community.region.vo.CommunityVO;
import com.smart.community.commons.exception.BusinessException;
import com.smart.community.region.vo.CommunityDeleteImpactVO;

import java.util.List;

/**
 * 社区管理服务接口
 *
 * @author Wu.Liang
 * @since 2024-12-21
 */
public interface ICommunityService extends IService<Community> {

    // ==================== 基础CRUD方法 ====================

    /**
     * 分页查询社区列表
     *
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    PageResult<CommunityVO> getCommunityPage(CommunityQueryDTO queryDTO) throws Exception;

    /**
     * 查询社区列表
     *
     * @param queryDTO 查询条件
     * @return 社区列表
     */
    List<CommunityVO> getCommunityList(CommunityQueryDTO queryDTO) throws Exception;

    /**
     * 根据ID查询社区
     *
     * @param communityId 社区ID
     * @return 社区信息
     */
    CommunityVO getCommunityById(Long communityId) throws Exception;

    /**
     * 根据编码查询社区
     *
     * @param communityCode 社区编码
     * @return 社区信息
     */
    CommunityVO getCommunityByCode(String communityCode) throws Exception;

    /**
     * 新增社区
     *
     * @param communityDTO 社区信息
     * @return 操作结果
     */
    Result<CommunityVO> addCommunity(CommunityDTO communityDTO) throws Exception;

    /**
     * 更新社区
     *
     * @param communityDTO 社区信息
     * @return 操作结果
     */
    Result<CommunityVO> updateCommunity(CommunityDTO communityDTO) throws Exception;

    /**
     * 删除社区
     *
     * @param communityId 社区ID
     * @return 操作结果
     */
    Result<Void> deleteCommunity(Long communityId) throws Exception;

    /**
     * 批量删除社区
     *
     * @param communityIds 社区ID列表
     * @return 操作结果
     */
    Result<Void> batchDeleteCommunity(List<Long> communityIds) throws Exception;

    /**
     * 删除社区（带关联处理）
     * 
     * @param communityId 社区ID
     * @param currentUserId 当前用户ID
     * @return 删除结果
     * @throws BusinessException 业务异常
     */
    String deleteCommunityWithRelations(Long communityId, Long currentUserId) throws BusinessException;

    /**
     * 批量删除社区（带关联处理）
     * 
     * @param communityIds 社区ID列表
     * @param currentUserId 当前用户ID
     * @return 删除结果
     * @throws BusinessException 业务异常
     */
    String batchDeleteCommunitiesWithRelations(List<Long> communityIds, Long currentUserId) throws BusinessException;

    /**
     * 检查删除影响
     * 
     * @param communityId 社区ID
     * @return 删除影响分析
     */
    CommunityDeleteImpactVO checkDeleteImpact(Long communityId);

    // ==================== 查询方法 ====================

    /**
     * 根据用户权限查询社区列表
     *
     * @param userId 用户ID
     * @return 有权限的社区列表
     */
    List<CommunityVO> getCommunityByUserPermission(Long userId) throws Exception;

    /**
     * 根据区域ID查询社区列表
     *
     * @param regionId 区域ID
     * @return 社区列表
     */
    List<CommunityVO> getCommunityByRegionId(Long regionId) throws Exception;

    /**
     * 根据区域ID获取社区列表
     *
     * @param regionId 区域ID
     * @return 社区列表
     */
    List<Community> getCommunitiesByRegion(Long regionId) throws Exception;

    /**
     * 获取社区楼栋列表
     *
     * @param communityId 社区ID
     * @return 楼栋列表
     */
    List<Building> getCommunityBuildings(Long communityId) throws Exception;

    // ==================== 状态管理方法 ====================

    /**
     * 更新社区状态
     *
     * @param communityId 社区ID
     * @param status 状态
     * @return 是否成功
     */
    boolean updateCommunityStatus(Long communityId, Integer status) throws Exception;

    /**
     * 批量更新社区状态
     *
     * @param communityIds 社区ID列表
     * @param status 状态
     * @return 是否成功
     */
    boolean batchUpdateCommunityStatus(List<Long> communityIds, Integer status) throws Exception;

    /**
     * 批量删除社区
     *
     * @param communityIds 社区ID列表
     * @return 是否成功
     */
    boolean batchDeleteCommunities(List<Long> communityIds) throws Exception;

    // ==================== 统计方法 ====================

    /**
     * 获取社区统计信息
     *
     * @param communityId 社区ID
     * @return 统计信息
     */
    Object getCommunityStats(Long communityId) throws Exception;

    // ==================== 验证方法 ====================

    /**
     * 检查社区编码唯一性
     *
     * @param communityCode 社区编码
     * @param excludeCommunityId 排除的社区ID
     * @return 是否唯一
     */
    boolean checkCommunityCodeUnique(String communityCode, Long excludeCommunityId) throws Exception;

    /**
     * 统计社区数量
     *
     * @param regionId 区域ID（可选）
     * @param communityType 社区类型（可选）
     * @return 社区数量
     */
    Long countCommunities(Long regionId, Integer communityType) throws Exception;

    // ==================== 缓存方法 ====================

    /**
     * 清除社区缓存
     *
     * @param communityId 社区ID
     */
    void clearCommunityCache(Long communityId) throws Exception;

    /**
     * 清除所有社区缓存
     */
    void clearAllCommunityCache() throws Exception;

    // ==================== Feign接口专用方法 ====================

    /**
     * 获取所有启用的社区列表（Feign接口专用，跳过权限验证）
     *
     * @return 启用的社区列表
     */
    List<CommunityVO> getAllEnabledCommunitiesForFeign() throws Exception;

    /**
     * 根据社区ID获取社区信息（Feign接口专用，跳过权限验证）
     *
     * @param communityId 社区ID
     * @return 社区信息
     */
    com.smart.community.feign.region.dto.CommunityInfoDTO getCommunityByIdForFeign(Long communityId) throws Exception;

    /**
     * 批量根据社区ID获取社区信息（Feign接口专用，跳过权限验证）
     *
     * @param communityIds 社区ID列表
     * @return 社区信息列表
     */
    List<com.smart.community.feign.region.dto.CommunityInfoDTO> getCommunitiesByIdsForFeign(List<Long> communityIds) throws Exception;
} 